<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<meta charset="utf-8" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="pandoc" />

<meta name="viewport" content="width=device-width, initial-scale=1">

<meta name="author" content="Greg Finak gfinak@fredhutch.org" />

<meta name="date" content="2018-10-24" />

<title>The DataPackageR YAML configuration file.</title>



<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
a.sourceLine { display: inline-block; line-height: 1.25; }
a.sourceLine { pointer-events: none; color: inherit; text-decoration: inherit; }
a.sourceLine:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode { white-space: pre; position: relative; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
code.sourceCode { white-space: pre-wrap; }
a.sourceLine { text-indent: -1em; padding-left: 1em; }
}
pre.numberSource a.sourceLine
  { position: relative; left: -4em; }
pre.numberSource a.sourceLine::before
  { content: attr(data-line-number);
    position: relative; left: -1em; text-align: right; vertical-align: baseline;
    border: none; pointer-events: all; display: inline-block;
    -webkit-touch-callout: none; -webkit-user-select: none;
    -khtml-user-select: none; -moz-user-select: none;
    -ms-user-select: none; user-select: none;
    padding: 0 4px; width: 4em;
    color: #aaaaaa;
  }
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
div.sourceCode
  {  }
@media screen {
a.sourceLine::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>



<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#header {
text-align: center;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; }  code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>

</head>

<body>




<h1 class="title toc-ignore">The DataPackageR YAML configuration file.</h1>
<h4 class="author"><em>Greg Finak <a href="mailto:gfinak@fredhutch.org" class="email">gfinak@fredhutch.org</a></em></h4>
<h4 class="date"><em>2018-10-24</em></h4>


<div id="TOC">
<ul>
<li><a href="#configuring-and-controlling-datapackager-builds.">Configuring and controlling DataPackageR builds.</a><ul>
<li><a href="#the-datapackager.yml-file.">The <code>datapackager.yml</code> file.</a></li>
<li><a href="#yaml-config-file-properties.">YAML config file properties.</a></li>
<li><a href="#editing-the-yaml-config-file.">Editing the YAML config file.</a><ul>
<li><a href="#api-calls">API calls</a></li>
</ul></li>
</ul></li>
</ul>
</div>

<div id="configuring-and-controlling-datapackager-builds." class="section level1">
<h1>Configuring and controlling DataPackageR builds.</h1>
<p>Data package builds are controlled using the <code>datapackager.yml</code> file.</p>
<p>This file is created in the package source tree when the user creates a package using <code>datapackage_skeleton()</code>.</p>
<p>It is automatically populated with the names of the <code>code_files</code> and <code>data_objects</code> the passed in to datapackage_skeleton.</p>
<div id="the-datapackager.yml-file." class="section level2">
<h2>The <code>datapackager.yml</code> file.</h2>
<p>The structure of a correctly formatted <code>datapackager.yml</code> file is shown below:</p>
<pre><code>configuration:
  files:
    subsetCars.Rmd:
      enabled: yes
  objects: cars_over_20
  render_root:
    tmp: &#39;450393&#39;</code></pre>
</div>
<div id="yaml-config-file-properties." class="section level2">
<h2>YAML config file properties.</h2>
<p>The main section of the file is the <code>configuration:</code> section.</p>
<p>It has three properties:</p>
<ul>
<li><p><code>files:</code></p>
<p>The files (<code>R</code> or <code>Rmd</code>) to be processed by DataPackageR. They are processed in the order shown. Users running multi-script workflows with dependencies between the scripts need to ensure the files are processed in the correct order.</p>
<p>Here <code>subsetCars.Rmd</code> is the only file to process. The name is transformed to an absolute path within the package.</p>
<p>Each file itself has just one property:</p>
<!-- - `name:`  -->
<p><!-- The name of the file. This is transformed to an absolute path within the package. --></p>
<ul>
<li><code>enabled:</code> A logical <code>yes</code>, <code>no</code> flag indicating whether the file should be rendered during the build, or whether it should be skipped. This is useful for ‘turning off’ long running processing tasks if they have not changed. Disabling processing of a file will not overwrite existing documentation or data objecs created during previous builds.</li>
</ul></li>
<li><p><code>objects:</code></p>
The names of the data objects created by the processing files, to be stored in the package. These names are compared against the objects created in the render environment by each file. They names must match.</li>
<li><p><code>render_root:</code></p>
<p>The directory where the <code>Rmd</code> or <code>R</code> files will be rendered. Defaults to a randomly named subdirectory of <code>tempdir()</code>. Allows workflows that use multiple scripts and create file system artifacts to function correctly by simply writing to and reading from the working directory.</p></li>
</ul>
</div>
<div id="editing-the-yaml-config-file." class="section level2">
<h2>Editing the YAML config file.</h2>
<p>The structure of the YAML is simple enough to understand but complex enough that it can be a pain to edit by hand.</p>
<p>DataPackageR provides a number of API calls to construct, read, modify, and write the yaml config file.</p>
<div id="api-calls" class="section level3">
<h3>API calls</h3>
<div id="construct_yml_config" class="section level4">
<h4><code>construct_yml_config</code></h4>
<p>Make an r object representing a YAML config file.</p>
<div id="example" class="section level5">
<h5>Example</h5>
<p>The YAML config shown above was created by:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb2-1" data-line-number="1"><span class="co"># Note this is done by the datapackage_skeleton. </span></a>
<a class="sourceLine" id="cb2-2" data-line-number="2"><span class="co"># The user doesn&#39;t usually need to call </span></a>
<a class="sourceLine" id="cb2-3" data-line-number="3"><span class="co"># construct_yml_config()</span></a>
<a class="sourceLine" id="cb2-4" data-line-number="4">yml &lt;-<span class="st"> </span>DataPackageR<span class="op">::</span><span class="kw">construct_yml_config</span>(</a>
<a class="sourceLine" id="cb2-5" data-line-number="5">  <span class="dt">code =</span> <span class="st">&quot;subsetCars.Rmd&quot;</span>,</a>
<a class="sourceLine" id="cb2-6" data-line-number="6">  <span class="dt">data =</span> <span class="st">&quot;cars_over_20&quot;</span></a>
<a class="sourceLine" id="cb2-7" data-line-number="7">  )</a></code></pre></div>
</div>
</div>
<div id="yml_find" class="section level4">
<h4><code>yml_find</code></h4>
<p>Read a yaml config file from a package path into an r object.</p>
<div id="example-1" class="section level5">
<h5>Example</h5>
<p>Read the YAML config file from the <code>mtcars20</code> example.</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb3-1" data-line-number="1"><span class="co"># returns an r object representation of</span></a>
<a class="sourceLine" id="cb3-2" data-line-number="2"><span class="co"># the config file.</span></a>
<a class="sourceLine" id="cb3-3" data-line-number="3">mtcars20_config &lt;-<span class="st"> </span><span class="kw">yml_find</span>(</a>
<a class="sourceLine" id="cb3-4" data-line-number="4">  <span class="kw">file.path</span>(<span class="kw">tempdir</span>(),<span class="st">&quot;mtcars20&quot;</span>)</a>
<a class="sourceLine" id="cb3-5" data-line-number="5">  )</a></code></pre></div>
</div>
</div>
<div id="yml_list_objects" class="section level4">
<h4><code>yml_list_objects</code></h4>
<p>List the <code>objects</code> in a config read by <code>yml_find</code>.</p>
<div id="example-2" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb4-1" data-line-number="1">  <span class="kw">yml_list_objects</span>(yml)</a></code></pre></div>
<pre><code>
cars_over_20</code></pre>
</div>
</div>
<div id="yml_list_files" class="section level4">
<h4><code>yml_list_files</code></h4>
<p>List the <code>files</code> in a config read by <code>yml_find</code>.</p>
<div id="example-3" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb6-1" data-line-number="1">  <span class="kw">yml_list_files</span>(yml)</a></code></pre></div>
<pre><code>
subsetCars.Rmd</code></pre>
</div>
</div>
<div id="yml_disable_compile" class="section level4">
<h4><code>yml_disable_compile</code></h4>
<p>Disable compilation of named files in a config read by <code>yml_find</code>.</p>
<div id="example-4" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb8-1" data-line-number="1">yml_disabled &lt;-<span class="st"> </span><span class="kw">yml_disable_compile</span>(</a>
<a class="sourceLine" id="cb8-2" data-line-number="2">    yml,</a>
<a class="sourceLine" id="cb8-3" data-line-number="3">    <span class="dt">filenames =</span> <span class="st">&quot;subsetCars.Rmd&quot;</span>)</a></code></pre></div>
<pre><code>configuration:
  files:
    subsetCars.Rmd:
      enabled: no
  objects: cars_over_20
  render_root:
    tmp: &#39;912178&#39;</code></pre>
</div>
</div>
<div id="yml_enable_compile" class="section level4">
<h4><code>yml_enable_compile</code></h4>
<p>Enable compilation of named files in a config read by <code>yml_find</code>.</p>
<div id="example-5" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb10-1" data-line-number="1">yml_enabled &lt;-<span class="st"> </span><span class="kw">yml_enable_compile</span>(</a>
<a class="sourceLine" id="cb10-2" data-line-number="2">    yml,</a>
<a class="sourceLine" id="cb10-3" data-line-number="3">    <span class="dt">filenames =</span> <span class="st">&quot;subsetCars.Rmd&quot;</span>)</a></code></pre></div>
<pre><code>configuration:
  files:
    subsetCars.Rmd:
      enabled: yes
  objects: cars_over_20
  render_root:
    tmp: &#39;912178&#39;</code></pre>
</div>
</div>
<div id="yml_add_files" class="section level4">
<h4><code>yml_add_files</code></h4>
<p>Add named files to a config read by <code>yml_find</code>.</p>
<div id="example-6" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb12-1" data-line-number="1">yml_twofiles &lt;-<span class="st"> </span><span class="kw">yml_add_files</span>(</a>
<a class="sourceLine" id="cb12-2" data-line-number="2">    yml,</a>
<a class="sourceLine" id="cb12-3" data-line-number="3">    <span class="dt">filenames =</span> <span class="st">&quot;anotherFile.Rmd&quot;</span>)</a></code></pre></div>
<pre><code>configuration:
  files:
    subsetCars.Rmd:
      enabled: yes
    anotherFile.Rmd:
      enabled: yes
  objects: cars_over_20
  render_root:
    tmp: &#39;912178&#39;</code></pre>
</div>
</div>
<div id="yml_add_objects" class="section level4">
<h4><code>yml_add_objects</code></h4>
<p>Add named objects to a config read by <code>yml_find</code>.</p>
<div id="example-7" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb14"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb14-1" data-line-number="1">yml_twoobj &lt;-<span class="st"> </span><span class="kw">yml_add_objects</span>(</a>
<a class="sourceLine" id="cb14-2" data-line-number="2">    yml_twofiles,</a>
<a class="sourceLine" id="cb14-3" data-line-number="3">    <span class="dt">objects =</span> <span class="st">&quot;another_object&quot;</span>)</a></code></pre></div>
<pre><code>configuration:
  files:
    subsetCars.Rmd:
      enabled: yes
    anotherFile.Rmd:
      enabled: yes
  objects:
  - cars_over_20
  - another_object
  render_root:
    tmp: &#39;912178&#39;</code></pre>
</div>
</div>
<div id="yml_remove_files" class="section level4">
<h4><code>yml_remove_files</code></h4>
<p>Remove named files from a config read by <code>yml_find</code>.</p>
<div id="example-8" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb16"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb16-1" data-line-number="1">yml_twoobj &lt;-<span class="st"> </span><span class="kw">yml_remove_files</span>(</a>
<a class="sourceLine" id="cb16-2" data-line-number="2">    yml_twoobj,</a>
<a class="sourceLine" id="cb16-3" data-line-number="3">    <span class="dt">filenames =</span> <span class="st">&quot;anotherFile.Rmd&quot;</span>)</a></code></pre></div>
<pre><code>configuration:
  files:
    subsetCars.Rmd:
      enabled: yes
  objects:
  - cars_over_20
  - another_object
  render_root:
    tmp: &#39;912178&#39;</code></pre>
</div>
</div>
<div id="yml_remove_objects" class="section level4">
<h4><code>yml_remove_objects</code></h4>
<p>Remove named objects from a config read by <code>yml_find</code>.</p>
<div id="example-9" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb18-1" data-line-number="1">yml_oneobj &lt;-<span class="st"> </span><span class="kw">yml_remove_objects</span>(</a>
<a class="sourceLine" id="cb18-2" data-line-number="2">    yml_twoobj,</a>
<a class="sourceLine" id="cb18-3" data-line-number="3">    <span class="dt">objects =</span> <span class="st">&quot;another_object&quot;</span>)</a></code></pre></div>
<pre><code>configuration:
  files:
    subsetCars.Rmd:
      enabled: yes
  objects: cars_over_20
  render_root:
    tmp: &#39;912178&#39;</code></pre>
</div>
</div>
<div id="yml_write" class="section level4">
<h4><code>yml_write</code></h4>
<p>Write a modified config to its package path.</p>
<div id="example-10" class="section level5">
<h5>Example</h5>
<div class="sourceCode" id="cb20"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb20-1" data-line-number="1"><span class="kw">yml_write</span>(yml_oneobj, <span class="dt">path =</span> <span class="st">&quot;path_to_package&quot;</span>)</a></code></pre></div>
<p>The <code>yml_oneobj</code> read by <code>yml_find()</code> carries an attribute that is the path to the package. The user doesn’t need to pass a <code>path</code> to <code>yml_write</code> if the config has been read by <code>yml_find</code>.</p>
</div>
</div>
</div>
</div>
</div>



<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>
